home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / lib.fmt / tcl / Interp.man < prev    next >
Encoding:
Text File  |  1991-10-10  |  7.1 KB  |  199 lines
  1.  
  2.  
  3.  
  4. Tcl_Interp            C Library Procedures             Tcl_Interp
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NNAAMMEE
  11.      Tcl_Interp - client-visible fields of interpreter structures
  12.  
  13. SSYYNNOOPPSSIISS
  14.      ##iinncclluuddee <<ttccll..hh>>
  15.  
  16.      typedef struct {
  17.           char *_r_e_s_u_l_t;
  18.           Tcl_FreeProc *_f_r_e_e_P_r_o_c;                                  |
  19.           int _e_r_r_o_r_L_i_n_e;
  20.      } Tcl_Interp;
  21.  
  22.      typedef void Tcl_FreeProc(char *_b_l_o_c_k_P_t_r);                    |
  23. _________________________________________________________________
  24.  
  25.  
  26. DDEESSCCRRIIPPTTIIOONN
  27.      The TTccll__CCrreeaatteeIInntteerrpp procedure returns a pointer to a
  28.      Tcl_Interp structure.  This pointer is then passed into
  29.      other Tcl procedures to process commands in the interpreter
  30.      and perform other operations on the interpreter.  Inter-
  31.      preter structures contain many many fields that are used by
  32.      Tcl, but only three that may be accessed by clients:          |
  33.      _r_e_s_u_l_t, _f_r_e_e_P_r_o_c, and _e_r_r_o_r_L_i_n_e.                              |
  34.  
  35.      The _r_e_s_u_l_t and _f_r_e_e_P_r_o_c fields are used to return results or  |
  36.      error messages from commands.  This information is returned   |
  37.      by command procedures back to TTccll__EEvvaall, and by TTccll__EEvvaall back  |
  38.      to its callers.  The _r_e_s_u_l_t field points to the string that   |
  39.      represents the result or error message, and the _f_r_e_e_P_r_o_c      |
  40.      field tells how to dispose of the storage for the string      |
  41.      when it isn't needed anymore.  The easiest way for command    |
  42.      procedures to manipulate these fields is to call procedures   |
  43.      like TTccll__SSeettRReessuulltt or TTccll__AAppppeennddRReessuulltt;  they will hide all   |
  44.      the details of managing the fields.  The description below    |
  45.      is for those procedures that manipulate the fields directly.  |
  46.  
  47.      Whenever a command procedure returns, it must ensure that     |
  48.      the _r_e_s_u_l_t field of its interpreter points to the string      |
  49.      being returned by the command.  The _r_e_s_u_l_t field must always  |
  50.      point to a valid string.  If a command wishes to return no    |
  51.      result then _i_n_t_e_r_p->_r_e_s_u_l_t should point to an empty string.   |
  52.      Normally, results are assumed to be statically allocated,     |
  53.      which means that the contents will not change before the      |
  54.      next time TTccll__EEvvaall is called or some other command procedure  |
  55.      is invoked.  In this case, the _f_r_e_e_P_r_o_c field must be zero.   |
  56.      Alternatively, a command procedure may dynamically allocate   |
  57.      its return value (e.g. using mmaalllloocc) and store a pointer to   |
  58.      it in _i_n_t_e_r_p->_r_e_s_u_l_t.  In this case, the command procedure    |
  59.      must also set _i_n_t_e_r_p->_f_r_e_e_P_r_o_c to the address of a procedure  |
  60.  
  61.  
  62.  
  63. Sprite v1.0                                                     1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. Tcl_Interp            C Library Procedures             Tcl_Interp
  71.  
  72.  
  73.  
  74.      that can free the value (usually ffrreeee).  If _i_n_t_e_r_p->_f_r_e_e_P_r_o_c  |
  75.      is non-zero, then Tcl will call _f_r_e_e_P_r_o_c to free the space    |
  76.      pointed to by _i_n_t_e_r_p->_r_e_s_u_l_t before it invokes the next com-  |
  77.      mand.  If a client procedure overwrites _i_n_t_e_r_p->_r_e_s_u_l_t when   |
  78.      _i_n_t_e_r_p->_f_r_e_e_P_r_o_c is non-zero, then it is responsible for      |
  79.      calling _f_r_e_e_P_r_o_c to free the old _i_n_t_e_r_p->_r_e_s_u_l_t (the          |
  80.      TTccll__FFrreeeeRReessuulltt macro should be used for this purpose).        |
  81.  
  82.      _F_r_e_e_P_r_o_c should have arguments and result that match the      |
  83.      TTccll__FFrreeeePPrroocc declaration above:  it receives a single argu-   |
  84.      ment which is a pointer to the result value to free.  In      |
  85.      most applications ffrreeee is the only non-zero value ever used   |
  86.      for _f_r_e_e_P_r_o_c.  However, an application may store a different  |
  87.      procedure address in _f_r_e_e_P_r_o_c in order to use an alternate    |
  88.      memory allocator or in order to do other cleanup when the     |
  89.      result memory is freed.                                       |
  90.  
  91.      As part of processing each command, TTccll__EEvvaall initializes      |
  92.      _i_n_t_e_r_p->_r_e_s_u_l_t and _i_n_t_e_r_p->_f_r_e_e_P_r_o_c just before calling the   |
  93.      command procedure for the command.  The _f_r_e_e_P_r_o_c field will   |
  94.      be initialized to zero, and _i_n_t_e_r_p->_r_e_s_u_l_t will point to an   |
  95.      empty string.  Commands that do not return any value can      |
  96.      simply leave the fields alone.  Furthermore, the empty
  97.      string pointed to by _r_e_s_u_l_t is actually part of an array of
  98.      TTCCLL__RREESSUULLTT__SSIIZZEE characters (approximately 200).  If a com-
  99.      mand wishes to return a short string, it can simply copy it
  100.      to the area pointed to by _i_n_t_e_r_p->_r_e_s_u_l_t.  Or, it can use
  101.      the sprintf procedure to generate a short result string at
  102.      the location pointed to by _i_n_t_e_r_p->_r_e_s_u_l_t.
  103.  
  104.      It is a general convention in Tcl-based applications that
  105.      the result of an interpreter is normally in the initialized
  106.      state described in the previous paragraph.  Procedures that
  107.      manipulate an interpreter's result (e.g. by returning an
  108.      error) will generally assume that the result has been ini-
  109.      tialized when the procedure is called.  If such a procedure
  110.      is to be called after the result has been changed, then
  111.      TTccll__RReesseettRReessuulltt should be called first to reset the result
  112.      to its initialized state.
  113.  
  114.      The _e_r_r_o_r_L_i_n_e field is valid only after TTccll__EEvvaall returns a
  115.      TTCCLL__EERRRROORR return code.  In this situation the _e_r_r_o_r_L_i_n_e
  116.      field identifies the line number of the command being exe-
  117.      cuted when the error occurred.  The line numbers are rela-
  118.      tive to the command being executed:  1 means the first line
  119.      of the command passed to TTccll__EEvvaall, 2 means the second line,
  120.      and so on.  The _e_r_r_o_r_L_i_n_e field is typically used in con-
  121.      junction with TTccll__AAddddEErrrroorrIInnffoo to report information about
  122.      where an error occurred.  _E_r_r_o_r_L_i_n_e should not normally be
  123.      modified except by TTccll__EEvvaall.
  124.  
  125.  
  126.  
  127.  
  128.  
  129. Sprite v1.0                                                     2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. Tcl_Interp            C Library Procedures             Tcl_Interp
  137.  
  138.  
  139.  
  140. KKEEYYWWOORRDDSS
  141.      free, initialized, interpreter, malloc, result
  142.  
  143.  
  144.  
  145.  
  146.  
  147.  
  148.  
  149.  
  150.  
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195. Sprite v1.0                                                     3
  196.  
  197.  
  198.  
  199.